home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 25 / Cream of the Crop 25.iso / os2 / srefv12i.zip / virtual.in < prev    next >
Text File  |  1997-03-21  |  8KB  |  166 lines
  1. ; SRE-FILTER support file -- specifying virtual directories. 3/97
  2. ;
  3. ; I) Introduction               ---------------------
  4. ;
  5. ;    Virtual directories are used to allow access to files not in a default directory.
  6. ;    The typical use is to allow requests for documents to be in a subdirectory
  7. ;    NOT under the "GoServe data directory".
  8. ;    Virtual files can also be for several other cases, including:
  9. ;           specifying the location of a  cgi-bin script
  10. ;           specifying the location of an sre-filter add-on
  11. ;           specifying where an uploaded file should be placed
  12. ;    Lastly, for some cases, virtual directories can be used to allow server
  13. ;    mediated access to files on other (remote) servers.
  14. ;
  15. ; II) Basic structure of entries   ----------------
  16. ;
  17. ; Each line in this file  should have the following structure:
  18. ;     host_nickname//  SEL_fragment  TARGET  limitation_list
  19. ; where:
  20. ;   * host_nickname// is optional
  21. ;   * SEL_fragment is the "beginning portion" of a request selector
  22. ;   * TARGET can be a (local) fully qualified directory or a
  23. ;                    (remote) fully specified URL
  24. ;   * the [optional] limitation_list is used to limit the applicability of the entry.
  25. ;     If present, it should be a spaced  delimited list. It's use is described below.
  26. ;
  27. ; III) How virtual directories work   ---------------
  28. ;
  29. ;   The SEL_fragment is compared to the beginning of the request selector (the
  30. ;   selector).  If an "abbreviation" match occurs, the
  31. ;   "fragment" is removed from the "request selector"
  32. ;   and replaced with either the (local) target "directory" OR the
  33. ;   (remote) target "URL".  The limitation_list (if present) is used to control
  34. ;   which entries are used, based on whether the request is asking for a document,
  35. ;   a server side program, or an upload (see section V below for details).
  36. ;   If this is confusing, the examples at the bottom of this document should help.
  37. ;
  38. ;                              
  39. ; IV) General Notes                             ------------------
  40. ;
  41. ;   * If  no match is found, a "default directory" is used.  In the typical case
  42. ;     of a document request on a single host server, the default directory is the
  43. ;     goserve data directory.
  44. ;
  45. ;   * The limitation list can be used to limit the "scope" of the entry.
  46. ;     In particular, the "default directory"  must match  one of the entries
  47. ;     in the limitation list.  If there is no limitation_list, the entry will
  48. ;     be used for all requests.
  49. ;
  50. ;   *  An asterisk (*) at the end of  directory name means "allow access to subdirectories".
  51. ;
  52. ;   *  Leading and trailing slashes in the SEL_fragment are ignored, and
  53. ;      / and \ are treated equivalently.  Similarly, trailing slashes in
  54. ;      the TARGET directory are ignored.
  55. ;      Thus, the following are all equivalent:
  56. ;          foobar1/   d:\foobar\*
  57. ;          foobar1    d:\foobar*
  58. ;          \foobar1\  d:\foobar*
  59. ;
  60. ;   *  If a Drive is not specified in the TARGET (local) directory, the drive that
  61. ;      SRE-filter is installed on will be used.
  62. ;
  63. ;   *   WARNING: The use of "REMOTE urls" is ONLY supported for document requests.
  64. ;             It is NOT supported for "server side include" files, such
  65. ;             as specified in the INCLUDE and INTERPRET keyphrases. Nor is it
  66. ;             supported for server side programs, or upload, requests.
  67. ;
  68. ;
  69. ; V) Using the limitation_list   ----------
  70. ;
  71. ;   The limitation_list is used to limit the applicability of a virtual directory
  72. ;   entry. For example, you may wish to have some virtual directories apply only
  73. ;   to document requests, and some only to upload requests. 
  74. ;   The limitation_list (if present) should contain any mixture of the following
  75. ;   special keywords:  !UPLOAD, !CGI-BIN, !ADDONS, and !HTML. 
  76. ;        !HTML    --- use this entry for document requests
  77. ;        !CGI-BIN --- use this entry for cgi-bin requests
  78. ;        !ADDONS  --- use this entry for sre-filter addons
  79. ;        !UPLOAD  --- use this entry for file uploads
  80. ;   Note that you can contain more then one entry in the "space delimited"
  81. ;   limitation list.  Including all four entries is the same as not having
  82. ;   a limitation list: the entry will be used for all requests.
  83. ;
  84. ;   For example:
  85. ;      scdemo d:\netdata\macros\scdemo !cgi-bin
  86. ;      scdemo d:\netdata\html\scdemo   !html
  87. ;   The first entry will be used when a request for a cgi-bin script arrives
  88. ;        (i.e.; scdemo/cgi-bin/scinit.cmd
  89. ;   The second will be used for document requests  
  90. ;        (i.e.; scdemo/foo1.htm)
  91. ;
  92. ;
  93. ; VI) Specifying remote "target urls"   -------------
  94. ;
  95. ;    i) the http:// MUST be present (otherwise SRE-Filter assumes you
  96. ;        are referring to a local directory name)
  97. ;    ii) conversion of  / does NOT occur for these entries
  98. ;   iii) the trailing * option is supported
  99. ;    iv) This is NOT a redirect! Rather, SRE-Filter will retrieve the file
  100. ;        represented by this URL (on a remote server), strip out the
  101. ;        response headers, and treat it as if it came from a local directory.
  102. ;
  103. ;
  104. ; VII)  Match precedence      ---------------
  105. ;  Unlike most other SRE-Filter files, match precedence for virtual directories
  106. ;  is based on "abbreviation" matching, not "best matching".  That is,
  107. ;  * wildcards should not be in the SEL_FRAGMENT.  Instead, SRE-Filter simply
  108. ;  uses the longest SEL_FRAGMENT that is an "abbreviation" for the request
  109. ;  selector.
  110. ;
  111. ;
  112. ; VIII) EXAMPLES --------------------------
  113. ;
  114. ; LOCAL/PROJECTS     D:\WORK\PROJECTS*
  115. ;    If a selector of: /LOCAL/PROJECTS/BOB/PLANE.HTM is recieved, the file
  116. ;    returned will be D:\WORK\PROJECTS\BOB\PLANE.HTM.
  117. ;
  118. ;    Note: If the * is removed, /LOCAL/PROJECTS/BOB/PLANE.HTM would generate
  119. ;       a "no access allowed" error (since access to subdirectory BOB, 
  120. ;        under WORK\PROJECTS, would not be allowed).
  121. ;
  122. ; Example of "no subdirectory allowed access"
  123. ;    STATES   D:\USA\MAINE
  124. ;    .. a selector of STATES/AG.HTM would be valid (and would
  125. ;       return D:\USA\MAINE\AG.HTM)
  126. ;
  127. ; Example of a remote target URL:
  128. ;    SERVER2 http://pc2.myorg.net/support1/
  129. ;    .. a selector of SERVER2/CANADA.HTM will cause SRE-Filter to request
  130. ;    /support1/canada.htm from pc2.myorg.net
  131. ;
  132. ;  Example of host-specific entry:
  133. ;     SWEETSHOP//  CANDY   E:\STORE1\PRODUCTS\CANDY\*
  134. ;      ... requests, to hosts with host_nickname of SWEETSHOP, that have
  135. ;      selectors beginning with CANDY refer to files in
  136. ;      E:\STORE1\PRODUCTS\CANDY (and it's subdirectories).
  137. ;
  138. ;  Example of a limitation list:
  139. ;           ACTION2 e:\programs\task1  !addons
  140. ;    The !addons signals that the ACTION2 "virtual directory" will only
  141. ;    be used for requests for sre-filter add-ons.
  142. ;      For example:
  143. ;      /action2/getafile?dir=foodir1
  144. ;         E:\programs\task1\GETAFILE.CMD would be executed (as an SRE-Filter add-on)
  145. ;      /action2/gogo.htm
  146. ;         D:\www\action2\gogo.htm would be returned (assuming that the GoServe data
  147. ;        directory is D:\www)
  148. ;  
  149. ; Some additional examples:
  150. ;
  151. ; Temp on C, but NO subdirectory access
  152. ; CTEMP C:\temp
  153. ;
  154. ; D:\work, with subdirectory access allowed.
  155. ;D\work D:\WORK\*
  156. ;
  157. ; Get from the EXPORT directory (and directories underneath EXPORT)
  158. ; on the server at www.ours.org
  159. ;SITE2 http://www.ours.org/export/*
  160. ;
  161. ; the D:\project1 directory (and subdirectories) contain html documents, and
  162. ; sre-filter add-on procedures.
  163. ; project1   d:\project1*  !HTML !ADDONS
  164. ;
  165. ; ---- End of comments
  166.